DEPRECATED

Deprecated APIs.

API REFERENCE

GENERAL

Introduction

SAP Concur APIs allow clients or partners to access data and functions within the SAP Concur product ecosystem. Through the use of these exposed endpoints and functions you can solve a vast array of different business issues and reporting needs such as:

• Pull data from SAP Concur for in-depth reporting services.
• Reconcile or validate your data by comparing SAP Concur data to what you have.
• Post new data into SAP Concur allowing for programmatic creation of information.
• Update existing information in SAP Concur to match your system data.

How to Use the APIs

SAP Concur APIs are accessed via an endpoint or URL. For some of our APIs the endpoint will accept parameters that will help refine the results being returned or allow for the insertion or update of data in the SAP Concur system.

Most of the SAP Concur APIs support four different types of requests:

• GET – Used to query information within the SAP Concur system.
• POST – Used to insert data into the SAP Concur system.
• PUT – Used to update existing information in the SAP Concur system.
• DELETE – Used to delete or deactivate existing information in the SAP Concur system.

SAP Concur also supports an alternative type of API referred to as a Callout. The Callout is a pre-configured step or condition that triggers SAP Concur to make a call out to your app to facilitate some sort of business transaction.

Explore the APIs

For the basic information on the APIs and what they do, you can check out the Swagger docs in API Explorer. Need more in-depth information? You can find information on each API using the links on the left side of the page. Finally, there are some Integration Guides that describe specific workflows. Even if none of them maps to your use case, they’re a good way to learn how to work with the SAP Concur APIs.

Resources

The information in these overviews will provide insight into what to expect during the certification process:

• Enterprise (B2B apps)
• eReceipt apps (B2C apps)

NOTE: These do not apply to a Triplink app integration.

HTTP Status Codes

Successful Requests

The web services return a HTTP 2xx response code when the request was successful.

HTTP Success Codes:

Failed Requests

The web service should return a response within 60 seconds. If the request times out without a response, the application should wait for 5 minutes then retry the request.

The web service returns a 4xx or 5xx HTTP response code when there are any errors and will include the following elements:

Error elements

Refer to the individual function documentation for function-specific error formats.

HTTP Error Codes

The full list of possible HTTP error codes can be found here. The table below provides additional details for commonly encountered error codes.

Locale Codes

All Concur customers have the following locale set in their entities by default. This is the only locale that is available for all clients.

Default Locale

Customers can request to have additional locales added to their entity if necessary. The following list includes all supported locales.

Spend Category Codes

The following table lists Spend Category codes that are used in several of the Concur APIs.

AUTHENTICATION

Authentication

Special Note (Please Read First)

If you are an existing partner with an existing app, please read both the Migration to Oauth2 Tokens and Getting Started documentation first. If you have any questions, please contact your Partner Enablement team representative before proceeding.

• Overview
• Tokens
  • Obtaining a token
  • Refreshing a token
  • Revoking a token
  • Token Management
  • Base URIs & Geolocation
  • ID Token
• Types of grants
  • Authorization grant
  • Password grant
  • Client Credentials grant
  • One Time Password grant
• Response Codes
• Troubleshooting

Note: The Pre-2017 Authorization (Deprecated) documentation be found here

Access Tokens

The Oauth2 service generates access tokens for authenticated users, applications or companies. The token returned in the Oauth2 response can be used to access protected resources on SAP Concur services.

The Oauth2 response can, depending on grant type contain these values:

Token Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close

{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "id_token": "ocid_token",
  "geolocation": "https://us.api.concursolutions.com"
}

Obtaining a token

You can obtain a token for three different types of principals in the SAP Concur universe.

• User
• Application
• Company

Token Lifetime

An accessToken has a one hour lifetime.

In order to obtain a token, the client application needs to call the Oauth2 endpoint using various grants depending on the authentication scenarios required. The full list of supported scenarios is provided below:

• Authorization grant
• Password grant
• Client Credentials grant
• One Time Password grant

Refreshing a token

The refresh grant is used to refresh an access_token that has expired. This grant can be used anytime a refresh_token is returned in the response of another grant request. No user interaction is required.

Token Lifetime

A refresh token has a six month lifetime. If the refresh token expires, the client application must reinitiate the authorization process. When a refresh token is used to request a new access token, both a new access token as well as a new refresh token are returned in the response. This token can change even if most of the time, this value is the same. Client applications should treat all returned refresh tokens as new tokens and overwrite the stored tokens with the new token from the response.

It is recommended that the client application use the refresh grant to request a new access token as the initial step of accessing protected resources of SAP Concur services.

Refreshing the token

To request a new access token using a valid refresh token, use the Oauth2 /token endpoint. Use the application/x-www-form-urlencoded content type.

POST /oauth2/v0/token

Post Body

Request

POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 437

POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&grant_type=refresh_token
&refresh_token=valid-refresh_token
&scope=app-scope

Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close

{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "id_token": "ocid_token",
  "geolocation": "https://us.api.concursolutions.com"
}

When the token has been refreshed, store the geolocation and the refresh token as they may have changed. On subsequant calls, use the last received golocation and refresh token.

Revoking a token

All refresh_tokens associated to a user for an application can be revoked by calling the https://us.api.concursolutions.com/app-mgmt/v0/connections endpoint with a DELETE action. You have to provide the User's accessToken in the Authorization Header as Authorization: Bearer <access_token>.

DELETE https://us.api.concursolutions.com/app-mgmt/v0/connections

Request

DELETE https://us.api.concursolutions.com/app-mgmt/v0/connections
Authorization: Bearer {token}

Response

HTTP/1.1 200 OK

Managing tokens

Refresh Tokens are strings that allow your application to obtain a fresh accessToken on behalf of a user to access SAP Concur APIs. The exact format of the string can change, but may look similar to the following:

e013335d-b4ce-4c43-a7e4-b67abc1adcb0

It is highly recommended that you store Refresh Tokens together with your user's authorization metadata in your application every time you obtain a new refreshToken as they might change depending on different scenarios.

FOR APP CENTER AND SUPPLIER PARTNERS supporting all geolocations, storing the authorization metadata, including the geolocation are REQUIRED.

Base URIs

When making API calls, the appropriate base URI should be used. There are three different scenarios: 1. Obtaining a token for a user. 2. Refreshing a token. 3. Calling other APIs.

The base URI for obtaining a token will leverage your application's geolocation. The base URI for refreshing tokens and all other API calls will leverage the token's geolocation.

Base URIs for Obtaining a Token

When your application is created, you will be provided with a client ID, secret and geolocation. When obtaining a token, your application should use the base URI for the geolocation in which your application exists.

There are two endpoints for each geolocation - one is the default (used for server-side calls) and the other should be used for client-side calls.

The full list of available token geolocations is available on the Base URIs page.

When obtaining the token, the token's geolocation will be included in the response. The token's geolocation should be stored along with the token. The Developer's app will then be able to make subsequent calls using the token and the correct end points based on the token's GEO location.

Base URIs for All Other Calls

When refreshing a token or when calling any other APIs, the token's geolocation should be used as the base URI.

Note: Client-side calls should use the www- variant of the base URI.

For example: When obtaining a token, if the response was the below:

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close

{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "id_token": "ocid_token",
  "geolocation": "https://us.api.concursolutions.com"
}

When then calling the receipts API to post a receipt, your request should be made to https://us.api.concursolutions.com (if server side) or https://www-us.api.concursolutions.com (for clients).

ID Token

Authentication service will return an OPENID compatible ID token with every token request. This id_token is primarily used to describe information about a user or a company. You can obtain the userId from this token.

Sample id_token:

{
  "aud": "e010e25d-b4ce-4ce3-a7e4-b670cb1adcb0",
  "concur.profile": "https://us.api.concursolutions.com/profile/v1/principals/76459ad3-f77b-4d98-a21a-55333c9179f0",
  "concur.version": 2,
  "concur.type": "user",
  "sub": "76459ad3-f77b-4d98-a21a-55333c9179f0",
  "iss": "https://us.api.concursolutions.com",
  "exp": 1485485529,
  "nbf": 1485481929,
  "at_hash": "351515a6482f4ee1",
  "iat": 1485481929
}

Verifying an id_token

The Authentication service exposes JWKs that can be used to validate the id_token in the form of a JWT. Validating a JWT is described in detail in RFC 7519 - sec 7.2

This is the link to the SAP Concur JSON Web Key for Oauth2. https://www-us.api.concursolutions.com/oauth2/v0/jwks

Authorization grant

The authorization grant is the regular 3-legged oauth2 grant and is defined in detail in RFC6749 sec-4.1. This grant requires the user to explicitly authenticate themselves and authorise the application initiating the grant.

The users must be able to authenticate themselves via an SAP Concur username & password. Users will be challenged to login by an Oauth2 HTML page.

Who should use it * 3rd party "partner" websites - or - * non-SAP Concur Applications - & - * Applications that need explicit user authentication & authorization - & - * Applications that can securely store a code, access_token & refresh_token

Grant details

Note that the grant type must be accessed using the www- version of the API Gateway in order to avoid certificate issues with some browsers. (ex: https://www-us.api.concursolutions.com instead of https://us.api.concursolutions.com)

GET /oauth2/v0/authorize

With this grant, the user has two authentication options: 1. Username and password 2. One-time link using a verified email address

With both options, once the user is successfully authenticated and the user authorizes your application, the user will be redirected to the redirect_URI specified in the initial /authorize call with a temporary token appended.

<redirect_uri>?geolocation=<token_geolocation>&code=<token>

If the user is not successfully authenticated or does not authorize the scopes for your application, an error code and description will be appended to the redirect URI. Please refer to the Response Codes section for more information.

Your application must then exchange the temporary token for a long-lived token using the below.

POST /oauth2/v0/token

Password grant

The Password grant can be used when there is a trust relationship between the user and the application. There are two credential types allowed with Password Grant:

1. "Password": with this credential type, the application either already has the user's credentials or can obtain the user's credentials by directly interacting with the user.
2. "AuthToken": This credential type is used for connections from the App Center. For App Center partners and TripLink suppliers, please refer to the certification documentation for more information.

Post Body

Request

POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 175

POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&grant_type=password
&username=username
&password=password

Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close

{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "id_token": "ocid_token",
  "geolocation": "https://us.api.concursolutions.com"
}

example bad login

{
  "error": "invalid_grant",
  "error_description": "Incorrect Credentials. Please Retry",
  "code": 5
}

Client Credentials grant

Use the application/x-www-form-urlencoded content type.

POST /oauth2/v0/token

Post Body

Request

POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 127

POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&grant_type=client_credentials

Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 1626
Connection: Close

{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "geolocation": "https://us.api.concursolutions.com"
}

One Time Password grant

The One-time Password grant type leverages email, phone (text messaging), instant messaging and similar systems to provide per user access tokens to client applications. This grant type requires the following steps:

1. The calling application calls the OAuth2 service specifying the otp grant type along with required parameters.
2. The OAuth2 service generates a one time token which it sends through the messaging mechanism chosen by the application.
3. The user retrieves the token and presents it to the application. The means of having this presented to the application is the responsibility of the application.
4. The application presents this one-time token to the OAuth2 service via the token endpoint.

Request a one-time token to be sent to the user

Use the application/x-www-form-urlencoded content type.

POST /oauth2/v0/otp

Post Body

The calling application code can also append n-number of unique client defined parameters in the URI for the purpose of connecting the one time token to the application when received by the user. The names of these parameters cannot conflict with the API defined parameters.

The following are reserved words and cannot be used as client application defined parameters:

/otp: "client_id" "client_secret" "channel_type" "channel_handle"

/token: "client_id" "client_secret" "channel_type" "channel_handle" "scope" "grant_type" "otp"

If the calling application chooses to send custom parameters, all of these exact same parameters must be included in subsequent API calls to acquire the access token. In other words, the URI signature, modulo the one time token parameter itself and token service specific parameters, must match the originating URI signature.

Request

POST /oauth2/v0/otp HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Host: us.api.concursolutions.com
Connection: close
Content-Length: 437

POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&channel_handle=email adress
&channel_type=valid-email
&link=https://example.com/callback

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 22
Date: date-requested

{
  "message": "otp sent"
}

Request an access token

The One Time Password grant requires that all of the parameters, including client application defined parameters to be sent in the request body when requesting an access token. Use the application/x-www-form-urlencoded content type.

POST oauth2/v0/token

Post Body

Request

POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 437

POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&channel_handle=email adress
&channel_type=valid-email
&scope=app_scope
&grant_type=otp
&otp=one-time-token

Response

HTTP/1.1 200 OK
Date: date-requested
Content-Length: 1490
Connection: keep-alive

{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "id_token": "ocid_token",
  "geolocation": "https://us.api.concursolutions.com"
}

Response Codes

HTTP Status returned by oauth2

4xx class errors have a JSON response with the following fields

{
  "code": <number>,
  "error": <error>,
  "error_description": <error_description>,
  "geolocation": <geolocation url where user lives>
}

/authorize

If the authorization or authentication are unsuccessful, your application will receive an error code and description at the redirect_uri provided.

 error_code=<>
 &error_description=<>

In all cases, the friendly error description should be displayed to the user.

/token

/otp

Troubleshooting

In order to assist with troubleshooting, SAP Concur responds with a unique correlationId in the response header. The key to look for is correlationid. This unique code can be used during troubleshooting as it identifies the API call in the log files. You should record this information in your own API call logs as well so that you can pass this information on to the SAP Concur support team.

Example of the correlationid in the response:

< HTTP/1.1 200 OK
< Server: cnqr-papeete
< Date: Mon, 04 Dec 2017 22:07:05 GMT
< Content-Type: application/json
< Content-Length: 2897
< Connection: keep-alive
< Concur-Correlationid: 2803b8f8-a42b-43c2-a739-b8768e4759b8

Enterprise Business Applications

Only the Password Grant Type is available for obtaining company-level tokens.

1. To begin the authentication flow, a Customer's SAP Concur Administrator clicks on the Connect button within the App Center listing and authorizes the partner's app. This app listing is located within customer's SAP Concur system's App Center tab.
2. The SAP Concur authorization service will redirect the Admin to the Partner’s Landing Page. Partners should follow the App Center UX Guidelines to create a web page that listens for an HTTP GET request from SAP Concur.
3. The redirect URI will contain an id, requestToken and userId parameters. Example: https://{partner_redirect_URI}?id=8568a4cd-8ffc-49d6-9417-be2d69aa075f&requestToken=5l85ae5a-426f-4d6f-8af4-08648c4b696b&userId=9bdded51-00b8-4f84-8bef-6d3afe727007
4. When the Partner application receives the redirect call, the Partner should strip the id and requestToken values from the URI and use those on a Post request to the SAP Concur Authorization service to obtain the official Oauth2 Access Token and Refresh Token for the customer using the password grant. As explained in detail in this presentation, the Partner must have Data Center Geo Awareness related to the token. We currently have 3 Data Centers and the API end points change based on these Data Centers so it is imperative the proper token management is followed. Otherwise, your app will not make the correct call per Access token.
5. An access token is valid for only one hour. The access token should be cached in memory and discarded after use.
6. After the Admin has successfully completed the login/enrollment process, the Partner should store the following elements with the customer’s profile metadata.
   • refresh_token: (36 characters including dashes) Valid for six months from the day and time issued.
   • refresh_expires_in: This is Epoch time format, convert to UTC.
   • geolocation: To be used when making API calls on behalf of the customer.
   • id: Aka sub, is the customer’s unique identifier (UUID). It can be retrieved from the following sources:
   • From the re-direct URI as the id element.
   • By decoding the id_token returned with Access token, as the sub element. (See https://jwt.io)
7. It is highly recommended that Partners log the following elements:
   • userId: the user who clicked on the Connect button (returned in the re-direct URI)
   • correlationid: SAP Concur responds with a unique code which identifies the API call in the log files. (returned in the response header). More details can be found here.

Learn More About Scopes

Partner Application Scope Usage

The table below lists all the possible scopes that an SAP Concur Partner Application might have access to. Please refer to the App Center Terms and Conditions and look under the "Shared Information" dialogue. Links to API endpoints that are accessible by each scope are mapped out.

Note:

• One scope may have access to more than one API/Endpoint.
• One scope may have both read and write access unless otherwise specified.
• The partner application does not necessarily use all the APIs that are available for a scope.

Company Level Authentication

• Overview
• Company
• Obtaining a one-time auth token
• Response Codes

Company

Company is a top-level principal within Concur and you would be able to obtain an access token and a refresh token on a Company's behalf just like you would be able to with a User. Only one authorization flow is currently available for obtaining tokens for a Company, which is the Password grant using a temporary auth token received from the App Center.

Obtaining an auth token

To begin the authentication flow for a company, one must first obtain a temporary auth token through AppCenter's interface. AppCenter will request for a temporary auth token and hand it off to the partner, who will then in turn use Password grant to exchange the temporary auth token for a full access token and refresh token for the company.

Auth tokens are valid only for 12 hours. Partners have 12 hours to exchange the auth token for a refresh and access token, and can use this auth token multiple times within the 12 hours in case of network failure.

This auth flow diagram describes this handshake:

Company Authentication Flow Sequence Diagram

AppCenter will call this endpoint to obtain an authToken.

POST /profile-service/v1/keys/principals/<companyId>/authtoken/

Sample Curl:

curl -E appcenter.p12:. -H 'concur-correlationid: githbuwiki' -XPOST https://us.api.concursolutions.com/profile-service/v1/keys/principals/08BCCA1E-0D4F-4261-9F1B-F778D96617D6/authtoken/

200 OK

{
  "status": "PASS",
  "code": 0,
  "errormsg": "",
  "token": "<authToken>"
}

AppCenter redirects User to Client's auth handler URI (Connect URL) and passing in the authToken

301 Redirect https://client.app.url?id=$company_uuid&requestToken=$request_token&userID=$user_uuid

At this point, the user should be prompted to sign in to your application. If the user doesn't not have account, the user should have the ability to create one. For applications that have user read scope, the User UUID can be used to pre-populate the account creation forms. Please see the App Center User Experience guidelines for more information.

Client app calls Oauth2 password grant to get an access token for the company

Example

Request

POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 175

client_id=your-client_id
&client_secret=your-client_secret
&grant_type=password
&username=<companyId>
&password=<authtoken>
&credtype=authtoken

Response

Success

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close

{
  "expires_in": "3600",
  "scope": "app_scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "geolocation":"https://us.api.concursolutions.com"
}

Failure

{
  "error": "invalid_grant",
  "error_description": "Incorrect Credentials. Please Retry",
  "code": 5
}

Response Codes

HTTP Status Code returned by oauth2

4xx class errors have a JSON response with the following fields

{
  "code": "<number>",
  "error": "<error>",
  "error_description": "<error_description>"
}

/token

GET Users Bulk API

• Obtain Company Token
• Calling Users Bulk API
• Schema

Obtain Company Token

Company is a top-level principal within SAP Concur and you would be able to obtain an access token and a refresh token on a company's behalf just like you would be able to with a user. Only one authorization flow is currently available for obtaining tokens for a company, which is the Password grant.

For more information and instructions for obtaining a Company Token, please review the Company Level Authentication

Calling Users Bulk API

This endpoint will retrieve a list of users that belong to a company and return basic company information together with the list of users.

Request

URI

Template

GET  /users/

Parameters

Example

Request

GET /users HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com

Sample Curl:

curl -v -X GET -H "Authorization: Bearer $token" \
-H "Accept: application/json" \
'https://us.api.concursolutions.com/users/?offset=0&limit=100&isactive=true'

Response

200 OK
{
  "total": 2,
  "offset": 0,
  "limit": 100,
  "company": {
    "name": "Company Name LLC",
    "address": "601 108th ave NE",
    "city": "Bellevue",
    "state": "WA",
    "zip": "98004",
    "country": "US"
  },
  "Items": [
    {
      "Active": true,
      "CountryCode": "US",
      "CellPhoneNumber": "5551234567",
      "PrimaryEmail": "johndoe@gmail.com",
      "EmployeeID": "johndoe@gmail.com",
      "ID": "99BFFFC3-C0BE-44FF-A441-AE1FFFFFF75B8",
      "Emails": ["PrimaryEmail", "VerifiedEmail", "email2", "email3", "email4", "email5"],
      "OrganizationUnit": null,
      "MiddleName": "",
      "LastName": "Doe",
      "FirstName": "John",
      "LoginID": "johndoe@gmail.com"
    },
    {
      "Active": true,
      "CountryCode": "US",
      "CellPhoneNumber": null,
      "PrimaryEmail": "janedoe@gmail.com",
      "EmployeeID": "janedoe@gmail.com",
      "ID": "55FFF504-C7B8-49FF-9E15-6248FFFFFCDB",
      "Emails": ["PrimaryEmail", "VerifiedEmail", "email2", "email3", "email4", "email5"],
      "OrganizationUnit": null,
      "MiddleName": "",
      "LastName": "Doe",
      "FirstName": "Jane",
      "LoginID": "janedoe@gmail.com"
    }
  ]
}

Schema

User

OAuth2 - Getting Started

The SAP Concur new Oauth2 framework is a very simple way to implement a Unified Token Authentication mechanism within your application. Here is a four step guide to helping you get up to speed and making calls to a SAP Concur API.

Note: The Pre-2017 Authorization (Deprecated) documentation can be found here

• Obtain Your Application clientID and clientSecret
• Obtaining an Access Token
• Calling an API with the Access Token
• Access Token Expiry and Obtaining a Fresh One

1. Obtain Your Application clientID and clientSecret

Before you can obtain an accessToken, you need to register an application with SAP Concur. You can do this by contacting your Partner Enablement Manager or Partner Account Manager. Once you have registered an application, you will receive a clientId, clientSecret and geolocation. The clientId is a unique UUID4 identifier for your application, and the clientSecret is your application's password. You will be using this credential to obtain tokens either for the application itself, or on behalf of a user. The geolocation is your default base URI for initiating all new connections.

2. Obtaining an Access Token

In order for an application to call a SAP Concur API, you need to obtain an accessToken on behalf of either a User, Company or Application. There are multiple ways of obtaining an accessToken through the various grants (Password, Authorization, Client Credentials, One-time Password) .

This section provides a quick start guide for generating an access token. If you are developing an application to be certified for the App Center or as a TripLink supplier, please refer to the certification documentation for the grant types your application must support.

For simplicity, we will use the Password grant flow as an example. The Password grant flow is used when you need to authenticate a user, using its username and password. This is typically reserved from SAP Concur applications (i.e. where the user's credentials will be captured and stored) but is used here for demonstration purposes.

When making the call, you will use your app's geolocation as the base URI followed by the endpoint. For example, if your geolocation is https://us.api.concursolutions.com, you will call https://us.api.concursolutions.com/oauth2/v0/token.

The first time you request for an accessToken a refreshToken is also returned. There are certain conditions where a refreshToken is not returned. This is used to get a new accessToken when one has expired. (see below for more info)

Example shell script using cURL to obtain an accessToken:

oauth2_base=https://us.api.concursolutions.com/oauth2
username=<concur_username> eg. john.doe@gmail.com
password=<password> eg. password1
client_id=<clientId> eg. e01f725d-b4ce-4ce3-a664-b670cb5876cb0
client_secret=<clientSecret> eg. 35c3bd92-fcb8-405e-a886-47ff3fba5664
curl -X POST -H 'concur-correlationid: nameofapp' "$oauth2_base/v0/token" --data "username=$username&password=$password&grant_type=password&client_secret=$client_secret&client_id=$client_id"

Full docs: https://developer.concur.com/api-reference/authentication/apidoc.html#password_grant

Store the token and geolocation.

3. Calling an API with the Access Token

Once you have the accessToken, you need to supply this in an Authorization header in the form of Authorization: Bearer <accessToken> when making a HTTPS call. The accessToken is a large string that looks something like this:

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjE0NTU2MTQzNDYifQ.eyJhdWQiOiIqIiwic3ViIjoiaHR0cDovL21zcGNzcHJzcnFhLmNvbmN1ci5jb25jdXJ0ZWNoLm9yZzozMDAzL3Byb2ZpbGUtc2VydmljZS92MS91c2Vycy83NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJpc3MiOiJodHRwczovL2NvbmN1ci5jb20iLCJleHAiOjE0NzM4OTUxMjksImxlZ2FjeV9hcHBsaWNhdGlvbl9pZCI6MTUwMDA2MzY1OSwidXNlclVSSSI6Imh0dHA6Ly9tc3Bjc3Byc3JxYS5jb25jdXIuY29uY3VydGVjaC5vcmc6MzAwMy9wcm9maWxlLXNlcnZpY2UvdjEvdXNlcnMvNzYwMDlBRDMtRjc3Qi00RDk4LUEyMUEtNTUzQzlDOTE3OUYwIiwidXNlcnV1aWQiOiI3NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJuYmYiOjE0NzM4OTE1MjksImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vYXBwIjoiaHR0cHM6Ly9hcGkuY29uY3Vyc29sdXRpb25zLmNvbS9hcHAtbWdtdC92MC9hcHBzL2UwMTBlMjVkLWI0Y2UtNGNlMy1hN2U0LWI2NzBjYjFhZGNiMCIsImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vc2NvcGVzIjpbIkNDQVJEIiwiQ09NUEQiLCJVU0VSIiwidXNlcl9yZWFkIiwiRU1FUkciLCJKT0JMT0ciLCJFUkVDUFQiLCJJVElORVIiLCJGSVNWQyIsIkxJU1QiLCJQQVNTViIsIkNPTkZJRyIsIkZPUCIsIkdIT1NUIiwiQ09OUkVRIiwiVFJJUElUIiwiQ09NUEFOWSIsInByb2ZpbGUiLCJFVlMiLCJlbWFpbCIsIlRSVlBUUyIsIkFUVEVORCIsIklOVlBPIiwiTk9USUYiLCJUUlZSRVEiLCJTVVBTVkMiLCJFWFBSUFQiLCJhZGRyZXNzIiwiRVhUUkNUIiwiUEFZQkFUIiwid3Jvbmdfc2NvcGUiLCJJTlZQTVQiLCJJTUFHRSIsIlRBWElOViIsIlJDVElNRyIsIlVOVVRYIiwiVFdTIiwiVE1DU1AiLCJCQU5LIiwiSU5WVkVOIiwib3BlbmlkIiwiTVRORyIsIklOU0dIVCIsIlRSVlBSRiIsIklOVlRWIiwiTUVESUMiLCJUU0FJIl0sImlhdCI6MTQ3Mzg5MTUyOX0.QHY4Mc5A3J981-HDv7KUdgS4tUI-qnmQAxwe9J6DHxuMmYSoGEYZ0dsnLnqc2lO2iVJK6Pg3EBZTArq8_vzV2FK7tA4-IT1eCEHo1e-RWZyWLnR7P56SvZozXpY73daovSH7572HrUm21FXcyLmdaLZyo2LfFcChaghbSCjm1Jg1duH-pLPUW4d89-_pdakmyxfV3GCm2N_XQXoRhNYAAiZcG8UfxEn3TpMHJ96F2n6keJanT_Sn2Sek_sH2EmeeCpg5-jDe0fvLvr1-gY5t0ifq8QBKWHSUUIrGbQvseD6CGzfyiFUqVypN2lukfWACR-26otN50c0OzY6kgY06RA

When you receive the accessToken, store it with the token's geolocation. That geolocation will be the base URI for all subsequent calls.

Armed with the accessToken you can start making calls to an SAP Concur API. Here's an example to retrieve profile information for a User in the Production environment using cURL (utilize the appropriate base URI geolocation for the token). Base URIs Reference:

curl -k -v -H "Accept: application/json" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjE0NTU2MTQzNDYifQ.eyJhdWQiOiIqIiwic3ViIjoiaHR0cDovL21zcGNzcHJzcnFhLmNvbmN1ci5jb25jdXJ0ZWNoLm9yZzozMDAzL3Byb2ZpbGUtc2VydmljZS92MS91c2Vycy83NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJpc3MiOiJodHRwczovL2NvbmN1ci5jb20iLCJleHAiOjE0NzM4OTUxMjksImxlZ2FjeV9hcHBsaWNhdGlvbl9pZCI6MTUwMDA2MzY1OSwidXNlclVSSSI6Imh0dHA6Ly9tc3Bjc3Byc3JxYS5jb25jdXIuY29uY3VydGVjaC5vcmc6MzAwMy9wcm9maWxlLXNlcnZpY2UvdjEvdXNlcnMvNzYwMDlBRDMtRjc3Qi00RDk4LUEyMUEtNTUzQzlDOTE3OUYwIiwidXNlcnV1aWQiOiI3NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJuYmYiOjE0NzM4OTE1MjksImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vYXBwIjoiaHR0cHM6Ly9hcGkuY29uY3Vyc29sdXRpb25zLmNvbS9hcHAtbWdtdC92MC9hcHBzL2UwMTBlMjVkLWI0Y2UtNGNlMy1hN2U0LWI2NzBjYjFhZGNiMCIsImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vc2NvcGVzIjpbIkNDQVJEIiwiQ09NUEQiLCJVU0VSIiwidXNlcl9yZWFkIiwiRU1FUkciLCJKT0JMT0ciLCJFUkVDUFQiLCJJVElORVIiLCJGSVNWQyIsIkxJU1QiLCJQQVNTViIsIkNPTkZJRyIsIkZPUCIsIkdIT1NUIiwiQ09OUkVRIiwiVFJJUElUIiwiQ09NUEFOWSIsInByb2ZpbGUiLCJFVlMiLCJlbWFpbCIsIlRSVlBUUyIsIkFUVEVORCIsIklOVlBPIiwiTk9USUYiLCJUUlZSRVEiLCJTVVBTVkMiLCJFWFBSUFQiLCJhZGRyZXNzIiwiRVhUUkNUIiwiUEFZQkFUIiwid3Jvbmdfc2NvcGUiLCJJTlZQTVQiLCJJTUFHRSIsIlRBWElOViIsIlJDVElNRyIsIlVOVVRYIiwiVFdTIiwiVE1DU1AiLCJCQU5LIiwiSU5WVkVOIiwib3BlbmlkIiwiTVRORyIsIklOU0dIVCIsIlRSVlBSRiIsIklOVlRWIiwiTUVESUMiLCJUU0FJIl0sImlhdCI6MTQ3Mzg5MTUyOX0.QHY4Mc5A3J981-HDv7KUdgS4tUI-qnmQAxwe9J6DHxuMmYSoGEYZ0dsnLnqc2lO2iVJK6Pg3EBZTArq8_vzV2FK7tA4-IT1eCEHo1e-RWZyWLnR7P56SvZozXpY73daovSH7572HrUm21FXcyLmdaLZyo2LfFcChaghbSCjm1Jg1duH-pLPUW4d89-_pdakmyxfV3GCm2N_XQXoRhNYAAiZcG8UfxEn3TpMHJ96F2n6keJanT_Sn2Sek_sH2EmeeCpg5-jDe0fvLvr1-gY5t0ifq8QBKWHSUUIrGbQvseD6CGzfyiFUqVypN2lukfWACR-26otN50c0OzY6kgY06RA" \
https://us.api.concursolutions.com/profile/v1/me

and the response will look like:

{
  "addresses": [
    {
      "type": "Home",
      "streetAddress": "",
      "locality": "",
      "region": "",
      "postalCode": "",
      "country": "US"
    },
    {
      "type": "Work",
      "streetAddress": "",
      "locality": "",
      "region": "",
      "postalCode": "",
      "country": "US"
    }
  ],
  "travelIds": {
    "userId": 85663431,
    "companyId": "63E447F6-A6A7-4B70-A951-10F45d693B43",
    "companyInternalId": 222458,
    "setId": 91157361,
    "ruleClassId": 394103,
    "travelConfigId": 0
  },
  "meta": {
    "created": "2016-06-08T00:00:00.000",
    "lastModified": "2016-08-22T14:32:00.000",
    "resourceType": "EnterpriseUser"
  },
  "displayName": "Brown",
  "name": {
    "formatted": "Brown, Terry ",
    "familyName": "Brown",
    "givenName": "Terry",
    "middleName": "",
    "honorificPrefix": "",
    "honorificSuffix": ""
  },
  "phoneNumbers": [
    {
      "type": "Home",
      "value": "tel:+1-4251231244",
      "primary": false,
      "notifications": false,
      "countryCode": "US",
      "countryISDCode": "1"
    },
    {
      "type": "Work",
      "value": "tel:+1-4251231234;ext=",
      "primary": false,
      "notifications": false,
      "countryCode": "US",
      "countryISDCode": "1"
    }
  ],
  "com:concur:Employee:1.0": {
    "employeeId": "brown@brown-sandbox.com",
    "jobTitle": "",
    "managerId": null,
    "orgUnitId": null
  },
  "dateOfBirth": null,
  "schemas": [
    "com:concur:User:1.0",
    "com:concur:Employee:1.0"
  ],
  "active": true,
  "id": "e01f725d-b4ce-4ce3-a664-b670cb5876cb0",
  "com:concur:TravelPreferences:1.0": {
    "air": {
      "seat": {
        "interrowPosition": null,
        "sectionPosition": null
      },
      "meal": "DontCare",
      "homeAirport": null
    },
    "rail": {
      "space": "DontCare",
      "meal": "DontCare",
      "bedCategory": "DontCare",
      "fareSpaceComfort": "DontCare",
      "deck": "DontCare",
      "coach": "DontCare",
      "bed": "DontCare",
      "berth": "DontCare",
      "noiseComfort": "DontCare",
      "contingency": "DontCare",
      "seat": "DontCare"
    },
    "car": {
      "smoking": "DontCare",
      "carType": "DontCare",
      "transmission": "DontCare",
      "gpsEnabled": false,
      "skirack": false
    },
    "hotel": {
      "earlyCheckin": false,
      "remark": null,
      "pool": false,
      "roomService": false,
      "foamPillows": false,
      "accessForBlind": false,
      "accessForWheelchair": false,
      "gym": false,
      "roomType": "DontCare",
      "restaurant": false,
      "rollawayBed": false,
      "smoking": "DontCare",
      "crib": false
    }
  },
  "gender": null,
  "emails": [
    {
      "value": "brown@brown-sandbox.com",
      "type": "Business",
      "notifications": true
    }
  ],
  "userType": "Enterprise"
}

Full docs: https://developer.concur.com/api-reference/user/

4. Access Token Expiry and Obtaining a Fresh One

Access Tokens have a default One hour lifetime. In order to obtain a fresh accessToken you need to call the auth endpoint using the Refresh Grant. This will return a brand new accessToken and a refreshToken. Refresh Tokens have a default 6 month lifetime. Clients will typically store the refreshToken together with the other user metadata like login information and unique identifiers.

Utilizing the geolocation for the token, here's an example of a cURL call to obtain a new accessToken

curl -X POST 'https://us.api.concursolutions.com/oauth2/v0/token' --data "client_id=$client_id&client_secret=$client_secret&grant_type=refresh_token&refresh_token=<old refresh token>"

Full docs: https://developer.concur.com/api-reference/authentication/apidoc.html#refresh_token

Now that you've made your first call, read up more about the SAP Concur APIs and how they can enhance your application or solve your business needs.

ref: https://developer.concur.com/api-reference/index.html

Migrating old tokens to new Oauth2 Bearer Tokens

• Base URIs
• Exchanging a Token
• Response Codes

Existing applications that use the Pre-2017 Authorization (Deprecated) framework need to move to support the new Oauth2 Bearer Tokens. Applications will need to migrate their existing users who already have connected to it to obtain new Oauth2 tokens without requiring users to reauthorize. This can be done by exchanging an old access token for a new refresh token.

Base URIs

When making API calls, the appropriate base URI for the user's geolocation should be used. See the Base URIs page for the full list.

Exchanging a Token

In order to support new Oauth2, applications need to exchange old access token for new accessToken and refreshToken pair. Once obtained, applications should store these refreshTokens as part of users authorization data.

The new Oauth2 accessToken has a one hour lifetime. Once expired, applications would need to call Oauth2's /v0/token endpoint using a refresh_grant, passing in the user's refreshtoken to obtain a fresh accessToken.

This is significantly different from how the deprecated /net2/Oauth2's method of handling access tokens. Partner's would have to store the new Oauth2 refreshToken instead of the old access token. Before making a call to any of the new v4 APIs, it is advisable to request for a new accessToken before making the API call.

Step 1: Obtain Application Token Clients can exchange OLD tokens for NEW Oauth2 tokens by calling the exchangeRefreshToken/me endpoint. In order to call this endpoint, you would first need to obtain an Application Token by calling the /v0/token endpoint with the client_credentials grant.

The endpoint also supports a parameter called "returnType=companyToken" This parameter allows a partner who already has what is known as a "WSAdmin" token for a client, to exchange that token for a Company level refresh token.

Step 2: Call exchangeRefreshToken

POST /appmgmt/v0/legacyApps/{OLDConsumerKey}/exchangeRefreshToken/me

If you are exchanging a WSAdmin token for a new Company level refresh token:

POST /appmgmt/v0/legacyApps/{OLDConsumerKey}/exchangeRefreshToken/me?returnType=companyToken

Request Header

Request Body

Sample Curl:

curl -H 'Authorization: Bearer <accessToken>' -d '{"token": "1_oaCof444CaiNXg1FFG$Perr19qIo", "secret": "12345"}' -X POST https://us.api.concursolutions.com/appmgmt/v0/legacyApps/Bwu0mvTHtKYAnBb3Pgu9AW/exchangeRefreshToken/me

successful call, responds with

200 OK
{
  "token": "8c844478-745c-4c45-adf7-1e2777a50dbf",
  "created": 1479407196809,
  "expired": 1494959196809,
  "scopes": [
    "EXPRPT",
    "LIST",
    "BANK",
    "CCARD"
  ],
  "context": "{\"userid\":\"7934467f-dcd1-4631-ba34-3ebd28343e8f\",\"cid\":\"3a55c75e-ac1e-4515-845c-0a4978452828\",\"ptype\":\"user\",\"userURI\":\"https://us.api.concursolutions.com/profile-service/v1/users/7934467f-dcd1-4631-ba34-3ebd28343e8f\",\"scope\":\"EXPRPT LIST BANK CCARD\"}"
}

Sample Curl for WSAdmin token exchange for Company level refreh token:

curl -H 'Authorization: Bearer <accessToken>' -d '{"token": "1_oaCof444CaiNXg1FFG$Perr19qIo", "secret": "12345"}' -X POST https://us.api.concursolutions.com/appmgmt/v0/legacyApps/Bwu0mvTHtKYAnBb3Pgu9AW/exchangeRefreshToken/me?returnType=companyToken

successful call, responds with

200 OK
{
  "token": "8c844478-745c-4c45-adf7-1e2777a50dbf",
  "created": 1479407196809,
  "expired": 1494959196809,
  "scopes": [
    "EXPRPT",
    "LIST",
    "BANK",
    "CCARD"
  ],
  "context": "{\"userid\":\"7934467f-dcd1-4631-ba34-3ebd28343e8f\",\"cid\":\"3a55c75e-ac1e-4515-845c-0a4978452828\",\"ptype\":\"company\",\"userURI\":\"https://us.api.concursolutions.com/profile-service/v1/users/7934467f-dcd1-4631-ba34-3ebd28343e8f\",\"scope\":\"EXPRPT LIST BANK CCARD\"}"
}

Step 3: Obtain New Access Token

Once you have the NEW refreshToken from the response (8c844478-745c-4c45-adf7-1e2777a50dbf) you can then proceed to call /v0/token using the refresh grant to obtain a NEW Oauth2 accessToken.

Sample Curl:

curl -X POST 'https://us.api.concursolutions.com/oauth2/v0/token' -d 'client_id=3a55c75e-ac1e-4515-845c-0a4978452828&client_secret=12345&grant_type=refresh_token&refresh_token=8c844478-745c-4c45-adf7-1e2777a50dbf'

successful call, responds with:

200 OK
{
  "expires_in": 3600,
  "scope": "EXPRPT LIST BANK CCARD",
  "token_type": "Bearer",
  "access_token": "eyJ0...demo...eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjE0NTU2MTQzNDYifQ.eyJjb25jdXIuc2NvcGVzIjpbIkVYUFJQVCIsIkxJU1QiLCJCQU5LIiwiQ0NBUkQiXSwiYXVkIjoiKiIsImNvbmN1ci5wcm9maWxlIjoiaHR0cHM6Ly91cy1ycWEzLmFwaS5jb25jdXJzb2x1dGlvbnMuY29tL3Byb2ZpbGUvdjEvcHJpY2lwYWxzLzc5NmI0NjdmLWRjZDEtNDYzMS1iYTg1LTNlYmQyOGIzNmU4ZiIsImNvbmN1ci52ZXJzaW9uIjoyLCJjb25jdXIudHlwZSI6InVzZXIiLCJjb25jdXIuYXBwIjoiaHR0cHM6Ly91cy1ycWEzLmFwaS5jb25jdXJzb2x1dGlvbnMuY29tL3Byb2ZpbGUvdjEvYXBwcy9lMDEwZTI1ZC1iNGNlLTRjZTMtYTdlNiLCJzdWIiOiI3OTZiNDY3Zi1kY2QxLTQ2MzEtYmE4NS0zZWJkMjhiMzZlOGYiLCJpc3MiOiJodHRwczovL3VzLXJxYTMuYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20iLCJleHAiOjE0Nzk0MTU4NjksImxlZ2FjeV9hcHBsaWNhdGlvbl9pZCI6MTUwMDA2MzY1OSwidXNlclVSSSI6Imh0dHBzOi8vdXMtcnFhMy5hcGkuY29uY3Vyc29sdXRpb25zLmNvbS9wcm9maWxlLXNlcnZpY2UvdjEvdXNlcnMvNzk2YjQ2N2YtZGNkMS00NjMxLWJhODUtM2ViZDI4YjM2ZThmIiwidXNlcnV1aWQiOiI3OTZiNDY3Zi1kY2QxLTQ2MzEtYmE4NS0zZWJkMjhiMzZlOGYiLCJuYmYiOjE0Nzk0MTIyNjksImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucyiaHR0cHM6Ly91cy1ycWEzLmFwaS5jb25jdXJzb2x1dGlvbnMuY29tL3Byb2ZpbGUvdjEvYXBwcy9lMDEwZTI1ZC1iNGNlLTRjZTMtYTdlNC1iNjcwY2IxYWRjYjAiLCJodHRwczovL2FwaS5jb25jdXJzb2x1dGlvbnMuY29tL3Njb3BlcyI6WyJFWFBSUFQiLCJMSVNUIiwiQkFOSyIsIkNDQVJEIl0sImlhdCI6MTQ3OTQxMjI2OX0.I4EeqKZbpfFonitGBZnLBb20NwMjZNNp5e1d3-BRsepEcJSVCVYIV9HAB2EkkopvoLJsAittiZgD0iDwuh2WVgUt_c4QGzNc_-rXRtCIeKyPQRvxUZNQ7y5RTqEQFNo7hrtXiNZ-yV30zlbijP-12XU5Cu4n2VXgRKxvcCUr5j0RcovUc6O0aOR7VTzj4ZbiDdijOEtmKWGluAYyfIlz8XF2aErAB5Jff2fr9UvgHgtbleYV7eBSesvd9hJEk4S-OAtmFoJwLDECLtLcBKyeHnPEe7LmkLYShcflWG2_tYk4ysPIMG6ne5kRNxJKsDbkMItjpXhujBEGi7YIPWtFWQ",
  "refresh_token": "31456dcd-b46a-4292-b2d3-f97033338487",
  "geolocation": "https://us.api.concursolutions.com"
}

Response Codes

HTTP Status returned by exchangeAccessToken

exchangeAccessToken Response Codes

HTTP Status returned by oauth2

4xx class errors have a JSON response with the following fields

{
  "code": <number>,
  "error": <error>,
  "error_description": <error_description>
}

/token

Oauth2 Migration Best Practices

• Old World Authentication
• New World Authentication
  • Oauth2
  • Getting Started
  • Token Management
  • Old Auth v.s. New Auth Diagram

Old World Authentication

• The old world authentication is a hybrid oauth2 implementation which has an endpoint that looks like this /net2/oauth2/
• Client applications are identified by a ConsumerKey and Secret pair. Sometimes these are referred to as client_id and client_secret.
• Access Tokens in the old world have a 12 months expiry period and refresh tokens live forever. This is typically not a good security practice and goes against the Oauth2 standards.
• Tokens that are being used by clients today are issued for WSADMINs, meaning all tokens have administrative access.

New World Authentication

1. Oauth2

• The SAP Concur new Oauth2 implementation follows the established Oauth2 Authorization Framework RFC : https://tools.ietf.org/html/rfc6749
• This new service has an endpoint of /oauth2/v0/token
• Unlike the old world auth, access tokens have a 1 hour expiry and refresh tokens have a 6 months expiry. This is in accordance to the best practice of using short lived tokens.
• This would mean that clients would need to perform token management.

2. Getting Started

• Getting clientID / clientSecret
  • Work with the SAP Concur implementation team to obtain a new oauth2 client_id and client_secret and to define the scope of client's application.
  • Process will take no longer than 48 hours.
  • Implementation Team will respond with new client_id, client_secret, company's refreshToken and expiry date.
  • Client stores and configures application with this info.
• Client applications should store the following tokens and data in their application.
  • Refresh Token: This token can change although most of the time this value is the same. Client applications should treat all returned refresh tokens as new values and overwrite the stored values with the new values you get from the response.
  • Refresh Token Expiry: This date should be checked by a daily script and ensure that a refresh_grant is made to keep the refresh token alive indefinitely. If company policy dictates that the token should be allowed to expire, then you can skip this step. Once a refresh token has expired, clients would need to contact SAP Concur's Implementation team to get a new company token.

3. Token Management

• Calling APIs with accessTokens

  • All APIs within SAP Concur require the calling application present an accessToken in the Header using the "Bearer" keyword.
  • Example: curl -k -v -H "Accept: application/json" \ -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjE0NTU2MTQzNDYifQ.eyJhdWQiOiIqIiwic3ViIjoiaHR0cDovL21zcGNzcHJzcnFhLmNvbmN1ci5jb25jdXJ0ZWNoLm9yZzozMDAzL3Byb2ZpbGUtc2VydmljZS92MS91c2Vycy83NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJpc3MiOiJodHRwczovL2NvbmN1ci5jb20iLCJleHAiOjE0NzM4OTUxMjksImxlZ2FjeV9hcHBsaWNhdGlvbl9pZCI6MTUwMDA2MzY1OSwidXNlclVSSSI6Imh0dHA6Ly9tc3Bjc3Byc3JxYS5jb25jdXIuY29uY3VydGVjaC5vcmc6MzAwMy9wcm9maWxlLXNlcnZpY2UvdjEvdXNlcnMvNzYwMDlBRDMtRjc3Qi00RDk4LUEyMUEtNTUzQzlDOTE3OUYwIiwidXNlcnV1aWQiOiI3NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJuYmYiOjE0NzM4OTE1MjksImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vYXBwIjoiaHR0cHM6Ly9hcGkuY29uY3Vyc29sdXRpb25zLmNvbS9hcHAtbWdtdC92MC9hcHBzL2UwMTBlMjVkLWI0Y2UtNGNlMy1hN2U0LWI2NzBjYjFhZGNiMCIsImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vc2NvcGVzIjpbIkNDQVJEIiwiQ09NUEQiLCJVU0VSIiwidXNlcl9yZWFkIiwiRU1FUkciLCJKT0JMT0ciLCJFUkVDUFQiLCJJVElORVIiLCJGSVNWQyIsIkxJU1QiLCJQQVNTViIsIkNPTkZJRyIsIkZPUCIsIkdIT1NUIiwiQ09OUkVRIiwiVFJJUElUIiwiQ09NUEFOWSIsInByb2ZpbGUiLCJFVlMiLCJlbWFpbCIsIlRSVlBUUyIsIkFUVEVORCIsIklOVlBPIiwiTk9USUYiLCJUUlZSRVEiLCJTVVBTVkMiLCJFWFBSUFQiLCJhZGRyZXNzIiwiRVhUUkNUIiwiUEFZQkFUIiwid3Jvbmdfc2NvcGUiLCJJTlZQTVQiLCJJTUFHRSIsIlRBWElOViIsIlJDVElNRyIsIlVOVVRYIiwiVFdTIiwiVE1DU1AiLCJCQU5LIiwiSU5WVkVOIiwib3BlbmlkIiwiTVRORyIsIklOU0dIVCIsIlRSVlBSRiIsIklOVlRWIiwiTUVESUMiLCJUU0FJIl0sImlhdCI6MTQ3Mzg5MTUyOX0.QHY4Mc5A3J981-HDv7KUdgS4tUI-qnmQAxwe9J6DHxuMmYSoGEYZ0dsnLnqc2lO2iVJK6Pg3EBZTArq8_vzV2FK7tA4-IT1eCEHo1e-RWZyWLnR7P56SvZozXpY73daovSH7572HrUm21FXcyLmdaLZyo2LfFcChaghbSCjm1Jg1duH-pLPUW4d89-_pdakmyxfV3GCm2N_XQXoRhNYAAiZcG8UfxEn3TpMHJ96F2n6keJanT_Sn2Sek_sH2EmeeCpg5-jDe0fvLvr1-gY5t0ifq8QBKWHSUUIrGbQvseD6CGzfyiFUqVypN2lukfWACR-26otN50c0OzY6kgY06RA" \ https://us.api.concursolutions.com/profile/v1/me
  • More documentation here: https://developer.concur.com/api-reference/authentication/getting-started.html

• Refreshing expired accessTokens

  • Since accessTokens have a one hour expiry, clients would need to get a new accessToken before any API call is made.
  • In order to obtain a new accessToken, clients should call Oauth2 using the refresh_grant and providing the old refreshToken and other additional fields.

  • In the error handling code, clients need to handle accessToken expiry errors. If the accessToken is expired in the middle of processing, the following should happen:

    • Code should call Oauth2's refresh_grant to get a new accessToken
    • Overwrite the existing refreshToken with the new one.
    • Update expiry date for refreshToken
    • Retry the API call.

  • More details about refreshing tokens here: https://developer.concur.com/api-reference/authentication/apidoc.html#refresh_token

• Handling errors

  • There are a few error codes that client applications should be aware of.
  • 403 Forbidden: Requesting for tokens for users who cannot be requested for. Usually for companies that are not authorized by their administrators.
  • The bulk of errors will be returned as 400 errors and the response contains a code and description. Client applications should look for these values to determine what to do next.

  Code	Desc	Comment
  05	Incorrect credentials.	clientID / secret not correct, or authtoken/password not correct
  10	Account is disabled
  14	Account is locked
  16	User lives elsewhere	There will be a geolocation field in the response to this error message. Use this as the base URL and retry the call.
  54	Invalid Scope	requested scope exceeds what is permitted.

  • for a full list, review this doc: https://developer.concur.com/api-reference/authentication/apidoc.html#response_codes

4. Old auth v.s. new auth diagram

List of Scopes for all SAP Concur APIs

• Naming Conventions
• List of v4 Actions
• List of v4 API Scopes
• List of Connect API scopes

Scope is a parameter as defined in the OAuth 2.0 standards (RFC6749) to enable a client to specify the scope of the access request. The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings although some implementations of scope uses a comma-delimited format. Scopes limit access for OAuth2 tokens and do not grant any additional permission beyond that which the client already has.

Scopes apply to applications only. Scopes play a crucial part in defining the ultimate access to a resource by a User.

User’s Roles / Permissions + Claims + Application Scopes

Naming Conventions

Concur services follow these standard naming conventions for scopes.

Template: {resource}.{optional subresource}.{action}
Examples: mileage.rate.read
          receipts.read

List of v4 Actions

{actions} are common authorizations across resources.

List of v4 API Scopes

These are the list of scopes for the v4+ APIs.

List of Connect API scopes

These are the list of scopes for the existing CONNECT APIs (v1.0 - v3.1)

Sign in with Concur

• Introduction
• Benefits
• Use Cases
• How it Works
• Getting Started
• Error Handling
  • Authorization Declined
  • Application is disabled
• Advanced
  • Enterprise Applications
  • TripLink Configurations
  • Supported Languages

Introduction

Streamline user onboarding with Sign in with Concur – a new feature that allows new users to log on to a partner application using their Concur credentials. Similar to the single sign-on feature provided by Facebook and other social applications, Sign in with Concur reduces the time and effort involved in setting up an account with our partner apps.

Benefits

For partners

• Streamlines account set-up: User's profile is pre-validated, including basic PII information plus travel preferences
• Simplifies development and integration: Quickly obtain authentication tokens for the user and call SAP Concur APIs

For users

• Quick and hassle-free way to sign up for a new app
• Secure: User's Concur credentials are never shared with partners

Use Cases

Sign in with Concur solves access and support issues for all of our various types of partner integrations:

Consumer applications

Business travelers use in-policy providers but may not have an existing loyalty account. Gain access to the network of business travelers and expense users of Concur by simplifying their first purchase.

Front office applications

Travel and Expense Policy administrators reduce the company's cost via volume purchasing through your application or service; reduce your integration and support overhead as well by removing the need to manage individual user accounts associate with those customers.

Back office applications

• Automate the process of provisioning users for your application using data from Concur.

• Simplify log in and support for users that log in infrequently by leveraging the SAP Concur authentication.

How it Works

Select Sign in with Concur from the site login menu

Pick Authentication Option

Single-sign on users can utilize the "Send a link to my email" option.

If the user selects "One-time Link":

Enter Email address

Confirmation page

Email example

If the user selects "Enter Concur Credentials":

Complete!

For both authentication flows, once authorized, the account is provisioned and user is logged in

Getting Started

1. Obtain your Application clientID and clientSecret

Before you can integrate Sign in with Concur into your application, you need to register your application with Concur. You can do this by contacting your Partner Enablement Manager or Partner Account Manager. Once you have registered an application, you will receive a clientId and clientSecret. The clientId is a unique UUID4 identifier for your application, and the clientSecret is your application password. You will be using this credential to obtain tokens either for the application itself, or on behalf of a user.

2. Add the button to your application

The first script adds the Concur style library to your page and the second applies the style to your button.

<script
  data-client-id=[yourClientID]
  data-redirect-uri=[yourRedirectURI]
  data-oauth-uri="https://www-us.api.concursolutions.com"
  src="https://static.concursolutions.com/nui/oauth/0.0.1/concur-signin.js">
</script>

<div style="float:right">
  <div id="concur-signin"></div>
</div>

Clicking this button renders the Sign in with Concur screen which presents two options to the user for signing in: 1) using Concur credentials OR 2) using a link sent via email.

Option 2 is designed for users who do not want to use passwords or those that do not have passwords such as Single Sign On (SSO) users.

3. Handle Authorization Completion

When users choose the email option, an email will be sent to the user that contains the redirect_uri chosen by the partner in Step 1. If the user selects the username and password option, after accepting the scopes, the user is also sent to the redirect_uri provided.

There will also be a temporary one-time use code which is appended to this redirect_uri. For example, if our redirect URI is https://www.hipmunk.com/auth/concur/callback, the code will be returned as:

https://www.hipmunk.com/auth/concur/callback?cc=<token>

The call to this redirect_uri will contain a temporary code cc which should be used to obtain an official oauth2 accesstoken and refreshtoken.

The response for a successful call will look like this:

**HTTP/** 1.1200 **OK**

;Content-Type: application/json

Date: date-requested

Content-Length: 3397

Connection: Close

{

  "expires_in":"3600",

  "scope":"app-scope",

  "token_type":"Bearer",

  "access_token":"new-access_token",

  "refresh_token":"new-refresh_token",

  "refresh_expiry":"refresh_token_expiry",

  "geolocation":"https://us.api.concursolutions.com"

}

4. Retrieve User Profile information

Once the partner completes the oauth2 flow, they receive an access_token and refresh_token. Using the access_token and within the hour lifetime of the token, the partner has the ability to call SAP Concur APIs. Your application may call the Profile API to obtain user information in order to provision an account in the partner's application.

TripLink Suppliers see the appendix for more details.

Here's an example to retrieve profile information for a User in the Production environment using cURL ( Base URIs for other Environments):

curl -k -v -H "Accept: application/json"\

-H "Authorization: Bearer …ypN2lukfWACR-26otN50c0OzY6kgY06RA"\

https://us.api.concursolutions.com/profile/v1/me

The response from the Profile service will be a compact version of the User profile. The schema can be found here.

5. Create user's account and log user into partner application immediately for a seamless user experience.

Once the user is logged in, your application must determine whether an existing account exists. Your application can do so by pulling user information from the application and SAP Concur profile.

Existing Accounts

For users connected to SAP Concur through the Concur App Center or otherwise, your application can match the SAP Concur unique user ID.

New SAP Concur Accounts

For users with existing, non-SAP Concur accounts , the unique user information in your application can be matched with information in SAP Concur (e.g. email address).

If the user does not have an existing account , your application must provision a user account. In this case, the partner maintains the user's profile over time. This is beneficial as it allows the app to post data for the user following the initial session. For example, it allows users make changes to a reservation and receive updates within SAP Concur and/or receive receipts for services charged after delivery such as hotel stays.

In all cases, the user's token, geolocation and user UUID should be stored. As applications vary in the information required to create a new user record and utilize the service, your application should leverage data from the user profile endpoint where possible.

Account Maintenance

Once the account is provisioned or matched, the application must:

• Provide the option to disconnect
• Maintain the user's session. Once the session is established, your application's typical session maintenance should be observed. This includes idle timeout and session refresh, where applicable. The issued token will have a predetermined expiration. To maintain the connection, please see the token refresh documentation.

Error Handling

In all cases, the error description provided by Concur should be displayed to the user.

The following covers special cases that require additional handling.

Authorization Declined

In the case the user leaves the sign in process or sign in is unsuccessful, the user will be redirected to the following:

Your_Redirect_Uri?

 error_code=user_denied

 &error_description=The+user+denied+your+request.

Apps should then provide the user with alternative connection methods:

• Log in by creating an account
• Attempt Sign in with Concur with an alternate credential

Application is disabled

Customers have the option to disable applications for their users. In these cases, the user will be redirected to the following:

Your_Redirect_Uri?

 error_code=

 &error_description=

In this case, the user will not be able to access your application using Sign in with Concur. The error description should be displayed to the user and the user given alternate sign in methods (e.g. create an account).

Advanced

This section covers guidelines for specific Sign in with Concur implementations.

Enterprise Applications

Company-wide integrations are unique in that your application will interact with SAP Concur both on a batch level (for example, GET or POST for multiple employees) but also allow individuals to sign in to the service without creating a new account.

When an application supports enterprise integrations, the user's account should be associated with the company's information (company UUID) so that the company token can be used to process batch transactions.

In addition, the administrator will need to identify the users which should have access to your application. Given that, the administrator must first add users to your service. An example of the set up and sign in process are documented below.

Sign in with Concur Set Up

The below diagram illustrates the initial set up process. To set up the connection, the administrator must identify the users of your service.

Note that, in addition to identifying users of the service, your application may also require that roles/permissions be assigned to individual users to determine access to various features and functionality of your service. Role and permissions assignment are not depicted in the diagram below as the requirements may differ for each client application.

Once added to the service, users must then verify their identity before first sign in. This process uses the One-Time Password Grant to first validate the user is the owner of the email address used to uniquely identify that individual. Once validated, the user may sign in with username and password going forward.

Signing in to the Client Application

When a user first navigates to your application, you may offer multiple sign in options, including Sign in with Concur. Once signed in, your application must validate that users have completed the one-time verification.

If the user has not completed the one-time verification when visiting your site, the One-Time Password Grant should be initiated on the user's behalf.

The below illustrates the process for users signing in to your service.

TripLink Configurations

Depending on the products the customer has enabled, integrations and features available with Sign in with Concur vary. The following defines the scopes that are applicable product combinations. Your application must support each of the below potential scope configurations:

• Travel Users
  • TripLink Access:
  • Travel Profile
  • Client Discount Code
  • User form of Payment
  • Ghost Card
  • Itinerary
  • E-Receipt
  • Non-Triplink Access:
  • Travel Profile
  • E-receipt
• Expense Only Access:*
  • E-receipt

* Special Note: For TripLink Suppliers that support the Travel Receipts API, this API does not support Expense only users. It is recommended that e-receipts be posted for these or all users via the Receipts API.

To determine which permissions the user has access to, each time a user signs in *, your application should:

1. Call the User Profile API to get the user's permissions.

A user can have one or more permissions that will dictate the scopes applicable to that user.

  curl -k -v -H "Accept: application/json"\

  -H "Authorization: Bearer …ypN2lukfWACR-26otN50c0OzY6kgY06RA"\

  https://us.api.concursolutions.com/api/user/v1.0/user

The detailed response can be found here: /api-reference/user/ (snippet below).

| Name | Type | Format | Description | | --- | --- | --- | --- | | ExpenseUser | string | | Whether the user has access to Expense. Format: Y/N. | | TripUser | string | | Whether the user has access to Travel. Format: Y/N. |

The response will indicate whether the is an Expense or Travel user.

If an expense user only , only the e-receipts scope is applicable and the user will not be eligible for other travel discounts or automated itinerary creation in Concur.

If a travel user, use the token to call the Travel Profile API .

Within this response, is the "HasOpenBooking" parameter; if "true" the user is eligible for TripLink.

If the user has travel only, they will not receive e-receipts.

1. Store the user permissions information. (optional)

The user's permissions can then be used to determine which scopes and APIs are applicable for updates to an existing booking and/or e-receipts.

• The user's permissions can change at any time. It is recommended that the permissions be checked each time the user logs in to determine whether new functionality is available to the user. *

Supported Languages

The following language codes are supported in by Sign in with Concur.

BUDGET

Budget v4 - Getting Started

• Overview
• Process Flow
• Products and Editions
• Scope Usage
• Dependencies
• Access Token Usage

Overview

The Budget service exposes budget and fiscal year data. Partners and clients may use the service endpoints to read and alter fiscal year, budget, budget adjustment, and budget matching configuration. Summary and detailed balance amounts are also available to read, but may not be altered via the API.

The sequence to configure budgets is to first setup the fiscal year and then the budget categories (if applicable) before creating budget items. Budget items may use budget tracking fields as filters. The budget tracking field can only be configured in the application UI. Also budget owner, approver, and budget viewer permissions have to be assigned to users prior to configuring budgets.

Process Flow

Products and Editions

• Concur Request Professional Edition
• Concur Request Standard Edition
• Concur Expense Professional Edition
• Concur Expense Standard Edition
• Concur Invoice Professional Edition
• Concur Invoice Standard Edition

Scope Usage

This API requires one or more of the following scopes:

Dependencies

SAP Concur clients must purchase Budget in order to use this API.

Access Token Usage

This API supports both company level and user level access tokens. The user needs to have the Budget Administrator role in order to access the API.

Budget v4 - Budget Adjustments

This resource is used to add budget adjustments. Each budget item detail may have one or more budget adjustments and adjustments can be made to manually add or subtract the budget, spent or pending balances.

• Create a Budget Adjustment
• Schema
  • Budget Adjustment
  • Error Response
  • Error Message

Create a Budget Adjustment

Create one or more budget adjustments.

• If the rolling adjustment feature is used, all adjustments for a given month, adjustment type, amount type, budget, and description will be combined into one adjustment. See Parameters below.
• The combination of budget item name, fiscal year name, fiscal period name, and owner email determine which budget the adjustment affects. See Schema below
• The amount type determines how the adjustment affects the budget. The budget amount adjustment reduces or increases the top-line budget amount while spent and pending amounts affect the budget balances.
• Adjustments may not be deleted or updated via the API.

Scopes

budgetitem.write - Refer to Scope Usage for full details.

Request

URI

Template

POST /budget/v4/adjustments

Parameters

Headers

• RFC 7235 Authorization
• RFC 7231 Content-Type

Payload

Budget Adjustments

Response

Status Codes

• 200 OK Successful call, response is in body.
• 400 Bad Request The request was determined to be invalid by the server. Possibly a validation failed on the data that was sent in the payload. The response will have a list of validation errors in the body. See below for an example 400 response.
• 403 Forbidden The user does not have the necessary permissions to perform the request.
• 404 Not Found The resource could not be found or does not exist.
• 500 Internal Server Error Error message in response body.
• 504 Gateway Timeout Error message in response body.

Headers

• concur-correlationid is a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
• RFC 7231 Allow
• RFC 7234 Cache-Control
• RFC 7230 Content-Length
• RFC 7231 Content-Type
• RFC 7231 Date
• RFC 7234 Expires
• RFC 7232 ETag
• RFC 7234 Pragma
• RFC 7231 Server
• RFC 7231 Vary

Payload

Either "Success" or an Error Response

Example

Request

POST https://us.api.concursolutions.com/budget/v4/adjustments?useMonthlyRollingUpdate=false
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

[
    {
        "budgetItemName":"API Budget-Oregon",
        "fiscalYearName": "2018",
        "budgetOwnerEmail": "m.jones@example.com",
        "fiscalPeriodName": "2018 - Q3",
        "amount": 100,
        "adjustmentType": "FUND_TRANSFER",
        "amountType": "BUDGET_AMOUNT",
        "description": "Initial July Adjustment",
        "transactionDate": "2018-07-11"
    },
    {
        "budgetItemName":"API Budget-Travel",
        "fiscalYearName": "2018",
        "budgetOwnerEmail": "m.jones@example.com",
        "fiscalPeriodName": "2018 - Q3",
        "amount": 100,
        "adjustmentType": "EXPENSE",
        "amountType": "SPENT_AMOUNT",
        "transactionDate": "2018-07-10"
    }
]

Response

Success Response

HTTP/1.1 200 OK
Cache-Control: no-store
Connection: keep-alive
Content-Length: 9
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:24:27 GMT
Expires: Thu, 20 Sep 2018 15:24:27 GMT
Pragma: no-cache
Vary: Origin
concur-correlationid: 86a0d9fe-9e98-43c3-89d8-a2917dd844cb

"Success"

Failure Response

HTTP/1.1 400 Bad Request
Cache-Control: no-store
Connection: close
Content-Length: 242
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:29:05 GMT
Expires: Thu, 20 Sep 2018 15:29:05 GMT
Pragma: no-cache
concur-correlationid: 561ce34c-6542-4bae-82a2-aa6ccd8c6b22

{
    "message": {  
        "status" : false,
        "errorMessageList" : [
          {
            "errorType" : "ERROR",
            "errorCode" : "BUDGET.BUDGET_PERIOD_REQUIRED",
            "errorMessage" : "Record 1) Record 1) Budget period is missing"
          }
        ]
    }
}

Schema

Budget Adjustment

Error Response

Error Message

Budget v4 - Budget Category

This resource is used to retrieve and update budget categories which are collections of expense types used for budget matching. Each budget item header may have one Budget Category. If it does, only line items with expense types contained in that Budget Category will be accumulated to the budget.

• GET All Budget Categories
• GET a Budget Category
• POST a Budget Category
• DELETE a Budget Category
• GET All Valid Expense Types
• Schema
  • Budget Category
  • Expense Type
  • Error Response
  • Error Message
• Response Headers

GET All Budget Categories

Retrieve a list of all budget categories.

Scopes

This API call requires one of the following scopes:

• budgetitem.read - Refer to Scope Usage for full details.
• budgetitem.write - Refer to Scope Usage for full details.

Request

URI

Template

GET /budget/v4/budgetCategory

Parameters

N/A

Headers

• RFC 7235 Authorization
• RFC 7231 Content-Type

Response

Status Codes

• 200 OK Successful call, response is in body.
• 400 Bad Request The request was determined to be invalid by the server.
• 403 Forbidden The user does not have the necessary permissions to perform the request.
• 500 Internal Server Error Error message in response body.
• 504 Gateway Timeout Error message in response body.

Headers

Response Headers

Payload

Budget Category

Example

Request

GET https://us.api.concursolutions.com/budget/v4/budgetCategory
Authorization: Bearer {token}
Content-Type: application/json

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1292
concur-correlationid: 9d59b6f0-e5bd-47bf-bcad-4c3de9f5c45c

[
    {
      "name":"Marketing and Outreach",
      "description":null,
      "statusType":"OPEN",
      "id":"36047f6c-6cf6-443d-a952-39efb012acdb",
      "expenseTypes":[
        {
          "featureTypeCode":"PURCHASE_REQUEST",
          "expenseTypeCode":"MKTG",
          "id":"f35827a8-7981-4a5b-bfc3-da7ebb4665ff",
          "name":null
        },
        {
          "featureTypeCode":"EXPENSE",
          "expenseTypeCode":"SEMNR",
          "id":"30f16783-e50e-4ab4-b6fb-f66cc75956f2",
          "name":null
        },
        {
          "featureTypeCode":"PURCHASE_REQUEST",
          "expenseTypeCode":"ADVT",
          "id":"64a04928-37b0-49c8-99e8-c346e6d47825",
          "name":null
        }
      ]
    },
    {
      "name":"Airfare",
      "description":null,
      "statusType":"OPEN",
      "id":"459fe79a-9b1e-4ea0-8416-19de0ff14eef",
      "expenseTypes":[
        {
          "featureTypeCode":"EXPENSE",
          "expenseTypeCode":"AIRFR",
          "id":"53300041-3fb9-4a93-8cdf-327fcbe74a0c",
          "name":null
        },
        {
          "featureTypeCode":"REQUEST",
          "expenseTypeCode":"AIRFR",
          "id":"29278c5a-624a-4dd6-a2c1-02dd233d3fbf",
          "name":null
        }
      ]
    }     
]

GET a Budget Category

Retreive the details of a single budget category.

Scopes

This API call requires one of the following scopes:

• budgetitem.read - Refer to Scope Usage for full details.
• budgetitem.write - Refer to Scope Usage for full details.

Request

URI

Template

GET  /budget/v4/budgetCategory/{id}

Parameters

Headers

• RFC 7235 Authorization
• RFC 7231 Content-Type

Response

Status Codes

• 200 OK Successful call, response is in body.
• 400 Bad Request The request was determined to be invalid by the server.
• 403 Forbidden The user does not have the necessary permissions to perform the request.
• 404 Not Found The resource could not be found or does not exist.
• 500 Internal Server Error Error message in response body.
• 504 Gateway Timeout Error message in response body.

Headers

Response Headers

Payload

Budget Category

Example

Request

GET https://us.api.concursolutions.com/budget/v4/budgetCategory/36047f6c-6cf6-443d-a952-39efb012acdb
Authorization: Bearer {token}
Content-Type: application/json

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 642
concur-correlationid: f7b1a193-46cc-4784-9c6f-d8e1e47ecaa1

{
  "name":"Marketing and Outreach",
  "description":null,
  "statusType":"OPEN",
  "id":"36047f6c-6cf6-443d-a952-39efb012acdb",
  "expenseTypes":[
    {
      "featureTypeCode":"PURCHASE_REQUEST",
      "expenseTypeCode":"MKTG",
      "id":"f35827a8-7981-4a5b-bfc3-da7ebb4665ff",
      "name":null
    },
    {
      "featureTypeCode":"EXPENSE",
      "expenseTypeCode":"SEMNR",
      "id":"30f16783-e50e-4ab4-b6fb-f66cc75956f2",
      "name":null
    },
    {
      "featureTypeCode":"PURCHASE_REQUEST",
      "expenseTypeCode":"ADVT",
      "id":"64a04928-37b0-49c8-99e8-c346e6d47825",
      "name":null
    }
  ]
}

POST a Budget Category

Save a new budget category or update an existing budget category.

• When adding expense types to a budget category, only the feature type code and expense type code are needed.
• Since Expense Report expense types are shared with Request and Payment Request (Invoice) expense types are shared with Purchase Request, only EXPENSE and PAYMENT_REQUEST expense types must be supplied. The types will be copied to REQUEST and PURCHASE REQUEST automatically.
• If an expense type is supplied but the feature is not enabled, it will have no effect. For example, an Invoice-Maintenance expense type can be added to a Budget Category if Invoice is not enabled for Budget--it will not change how spending is assigned to budgets.

Scopes

budgetitem.write - Refer to Scope Usage for full details.

Request

URI

Template

POST  /budget/v4/budgetCategory

Parameters

N/A

Headers

• RFC 7235 Authorization
• RFC 7231 Content-Type

Payload

Budget Category

Response

Status Codes

• 200 OK Successful call, response is in body.
• 400 Bad Request The request was determined to be invalid by the server. Possibly a validation failed on the data that was sent in the payload. The response will have a list of validation errors in the body. See below for an example 400 response.
• 403 Forbidden The user does not have the necessary permissions to perform the request.
• 404 Not Found The resource could not be found or does not exist.
• 500 Internal Server Error Error message in response body.
• 504 Gateway Timeout Error message in response body.

Headers

Response Headers

Payload

Budget Category or Error Response

Example

Request

POST https://us.api.concursolutions.com/budget/v4/budgetCategory
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Advertising Category",
  "description": "Advertising",
  "expenseTypes": [
    {
      "featureTypeCode": "EXPENSE",
      "expenseTypeCode": "ADVT"
    },
    {
      "featureTypeCode": "PAYMENT_REQUEST",
      "expenseTypeCode": "ADVT"
    }
  ],
  "statusType": "OPEN"
}

Response

Success Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: 5c00e59f-d00c-4019-8d3d-47130d8e37b4

{
  "name": "Advertising Category",
  "description": "Advertising",
  "id": "d9fd5191-7016-4f50-a6c8-4770bddc01d8",
  "statusType": "OPEN",
  "expenseTypes": [
    {
      "id": "e1dd44da-25b4-4180-8d89-00f3a8d8cf4e",
      "featureTypeCode": "EXPENSE",
      "expenseTypeCode": "ADVT",
      "name": null
    },
    {
      "id": "67253ac1-77e0-4d61-a478-0d194611b320",
      "featureTypeCode": "PAYMENT_REQUEST",
      "expenseTypeCode": "ADVT",
      "name": null
    }
  ]
}

Failure Response

HTTP/1.1 400 Bad Request
Cache-Control: no-store
Connection: close
Content-Length: 338
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:27:05 GMT
Expires: Thu, 20 Sep 2018 15:27:05 GMT
Pragma: no-cache
concur-correlationid: 44adb686-a624-4ee5-b618-e4ea31a95bec

{
  "status" : false,
  "errorMessageList" : [
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.BUDGET_CATEGORY_NAME_REQUIRED",
      "errorMessage" : "Budget category name is required"
    },
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.BUDGET_CATEGORY_NAME_UNIQUE_ERROR",
      "errorMessage" : "Budget category must have a unique name"
    }
  ]
}

DELETE a Budget Category

Delete a budget category. Budget categories that are in use by budget items may not be deleted.

Scopes

budgetitem.write - Refer to Scope Usage for full details.

Request

URI

Template

DELETE  /budget/v4/budgetCategory/{id}

Parameters

Headers

• RFC 7235 Authorization
• RFC 7231 Content-Type

Response

Status Codes

• 200 OK Successful call, response is in body.
• 400 Bad Request The request was determined to be invalid by the server.
• 403 Forbidden The user does not have the necessary permissions to perform the request.
• 404 Not Found The resource could not be found or does not exist.
• 500 Internal Server Error Error message in response body.
• 504 Gateway Timeout Error message in response body.

Headers

Response Headers

Example

Request

DELETE https://us.api.concursolutions.com/budget/v4/budgetCategory/a5e00b3f-b941-4522-8b0e-07412fb2cc7c
Authorization: Bearer {token}
Content-Type: application/json

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 0
concur-correlationid: 39216840-2808-4c49-8874-e9862d96fdb6

GET All Valid Expense Types

Retrieve a list of all possible expense types that may be used in a budget category.

• The list for REQUEST expense types is identical to the list for EXPENSE expense types and similarly PURCHASE_REQUEST is identical to PAYMENT_REQUEST. Due to response size and performance concerns, only EXPENSE and PAYMENT_REQUEST are returned and the caller should assume that identical expense types exist for REQUEST and PURCHASE_REQUEST.

Scopes

This API call requires one of the following scopes:

• budgetitem.read - Refer to Scope Usage for full details.
• budgetitem.write - Refer to Scope Usage for full details.

Request

URI

Template

GET  /budget/v4/budgetCategory/expenseTypes

Parameters

N/A

Headers

• RFC 7235 Authorization
• RFC 7231 Content-Type

Response

Status Codes

• 200 OK Successful call, response is in body.
• 400 Bad Request The request was determined to be invalid by the server.
• 403 Forbidden The user does not have the necessary permissions to perform the request.
• 500 Internal Server Error Error message in response body.
• 504 Gateway Timeout Error message in response body.

Headers

Response Headers

Payload

Expense Type

Example

Request

GET https://us.api.concursolutions.com/budget/v4/budgetCategory/expenseTypes
Authorization: Bearer {token}
Accept: application/json

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 367
concur-correlationid: 7afa7091-bc4e-4408-8248-a67f9e24a023

[
  {
    "featureTypeCode":"EXPENSE",
    "expenseTypeCode":"AIRFR",
    "id":null,
    "name":"Airfare"
  },
  {
    "featureTypeCode":"EXPENSE",
    "expenseTypeCode":"AIRTX",
    "id":null,
    "name":"Airfare Ticket Tax"
  },
  {
    "featureTypeCode":"PAYMENT_REQUEST",
    "expenseTypeCode":"CATER",
    "id":null,
    "name":"Catering"
  }
]

Schema

BudgetCategory

ExpenseType

Error Response